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Introduction 


About this book 


The Amiga Technical Reference Series is the official guide to programming Commodore’s Amiga 
computers. This volume, the Amiga ROM Kernel Reference Manual: Includes and Autodocs, contains 


alphabetically organized Autodoc function summaries and listings of the Amiga system include files. 


Autodocs are descriptions of the Amiga’s system functions. The include files list the Amiga’s system 
definitions and data structures. This revised edition has been updated for Release 2 of the Amiga 


operating system. 
This manual is the essential quick reference for all Amiga programmers. It contains: 


“J Summaries of the system library functions 

J Summaries of the system device commands 

_J Summaries of system resource calls 

_} Summaries of the amiga.lib functions and source code 

(1 C language include files (-h files) 

“1 Assembly language include files (.i files) 

"J Handy charts designed to ease debugging and exploring 


The other manuals in this series are the Amiga User Interface Style Guide, the Amiga ROM Kernel 
Reference Manual: Libraries, the Amiga ROM Kernel Reference Manual: Devices, and the Amiga Hardware 


Reference Manual. 


About the examples 


Except as noted, 68000 assembly language examples have been assembled under the Innovatronics CAPE 
assembler V2.x, the HiSoft Devpac assembler V1.2, and the Lake Forest Logic ADAPT assembler 1.0. No 


substantial changes should be required to switch between assemblers. 


C examples have been compiled under SAS C, version 5.10a and Manx Aztec C 68K, version 5.0d. 
Default compiler options are used in both cases. All the C examples assume that the automatic Ctrl-C 


feature of the compiler has been disabled. Add this code to each example to complete it: 
For SAS C (and Lattice C revisions 4.0 and greater) 


Compile with: lc -L <filename>.c 


/* Add this function before main(). This overrides the default 
* Lattice CTRL-C trap. If this function returns zero, then the 
* CTRL-C event will be ignored */ 


int CXBRK ( void ) { return(0); } 
int chkabort( void ) { return(0); } 
For Aztec C 


Compile with: cc <filename>.c 
ln <filename.o> -lc 


/* Add this near the top */ 
#include <functions.h> 


/* Add this before main() */ 
extern int Enable Abort; /* reference abort enable */ 


/* Add this after main(), as the first active line in the program */ 
Enable Abort=0; /* turn Off CTRU=C -*/ 


General Amiga development guidelines 


The environment of the Amiga computer is quite different than that of many other systems. The Amiga is 
a multitasking platform, which means multiple programs can run on a single machine simultaneously. 
However, for multitasking to work correctly, care must be taken to ensure that programs do not interfere 


with one another. It also means that certain guidelines must be followed during programming. 


I Check for memory loss. Operate your program, then exit. Write down the amount of free memory. 
Repeat the operation of your program and exit. The amount of free memory remaining should be 
exactly the same. Any difference indicates a serious problem in your cleanup. (Beware when 
checking the amount of free memory - some memory loss is normal the first time you open a 
device or disk-based library because the system has to allocate memory to accommodate them. 


That is why you should run the program once before checking free memory.) 


QO Use all of the program debugging and stress tools that are available when writing and testing your 
code. New debugging tools such as Enforcer, MungWall, and Scratch can help find uninitialized 
pointers, attempted use of freed memory and misuse of scratch registers or condition codes (even 


in programs that appear to work perfectly). 


() Always make sure you actually get any system resource that you ask for. This applies to memory, 
windows, screens, file handles, libraries, devices, ports, etc. Where an error value or return is 
possible, ensure that there is a reasonable failure path. Many poorly written programs will 
appear to be reliable, until some error condition (such as memory full or a disk problem) causes 


the program to continue with an invalid or null pointer, or branch to untested error handling 
code. 


Q Always clean up after yourself. This applies for both normal program exit and program termination 
due to error conditions. Anything that was opened must be closed, anything allocated must be 
deallocated. It is generally correct to do closes and deallocations in reverse order of the opens 
and allocations. Be sure to check your development language manual and startup code; some 
items may be closed or deallocated automatically for you, especially in abort conditions. If you 


write in the C language, make sure your code handles Ctrl-C properly. 


J Remember that memory, peripheral configurations, and ROMs differ between models and between 
individual systems. Do not make assumptions about memory address ranges, storage device 
names, or the locations of system structures or code. Never call ROM routines directly. Beware 
of any example code you find that calls routines at addresses in the $FO0000 - $FFFFFF range. 
These are ROM routines and they will move with every OS release. The only supported interface 


to system ROM code is through the library, device, and resource calls. 


LY Never assume library bases or structures will exist at any particular memory location. The only 
absolute address in the system is $00000004, which contains a pointer to the exec.library base. 
Do not modify or depend on the format of private system structures. This includes the poking of 


copper lists, memory lists, and library bases. 


_I Never assume that programs can access hardware resources directly. Most hardware is controlled 
by system software that will not respond well to interference from other programs. Shared 
hardware requires programs to use the proper sharing protocols. Use the defined interface; it is 


the best way to ensure that your software will continue to operate on future models of the Amiga. 


I Never access shared data structures directly without the proper mutual exclusion (locking). 


Remember that other tasks may be accessing the same structures. 


I The system does not monitor the size of a program’s stack. Take care that your program does not 
cause stack overflow, and provide enough extra stack space for the possibility that future 


revisions of system functions might require additional stack space. 


\ Never use a polling loop to test signal bits. If your program waits for external events like menu 
selection or keystrokes, do not bog down the multitasking system by busy-waiting in a loop. 


Instead, let your task go to sleep by Wait()ing on its signal bits. For example: 


Signals = (ULONG) Wait ( (1<<windowPtr->UserPort->mp SigBit) | 
(1<<consoleMsgPortPtr->mp_ SigBit) se 


This turns the signal bit number for each port into a mask, then combines them as the argument 
for the exec.library/Wait() function. When your task wakes up, handle all of the messages at 
each port where the SigBit is set. There may be more than one message per port, or no messages 
at the port. Make sure that you ReplyMsg() to all messages that are not replies themselves. If 
you have no signal bits to Wait() on, use Delay() or WaitTOF() to provide a measured delay. 


11 Tasks (and processes) execute in 680x0 user mode. Supervisor mode is reserved for interrupts, traps, 
and task dispatching. Take extreme care if your code executes in supervisor mode. Exceptions 


while in supervisor mode are deadly. 


1 Most system functions require a particular execution environment. All DOS functions and any 
functions that might call DOS (such as the opening of a disk-resident library, font, or device) can 
only be executed froma process. A task is not sufficient. Most other ROM kernel functions may 


be executed from tasks. Only a few may be executed from interrupts. 


Q Never disable interrupts or multitasking for long periods. If you use Forbid() or Disable(), you 
should be aware that execution of any system function that performs the Wait() function will 
temporarily suspend the Forbid() or Disable() state, and allow multitasking and interrupts to 
occur. Such functions include almost all forms of DOS and device I/O, including common 


“stdio” functions like printf(). 


LI Never tie up system resources unless it is absolutely necessary. For example, if your program does 
not require constant use of the printer, open the printer.device only when you need it. This will 
allow other tasks to use the printer while your program is running. You must provide a 


reasonable error response if a resource is not available when you need it. 


Q) All data for the custom chips must reside in Chip memory (type MEMF_CHIP). This includes 
bitplanes, sound samples, trackdisk buffers, and images for sprites, bobs, pointers, and gadgets. 
The AllocMem() call takes a flag for specifying the type of memory. A program that specifies 
the wrong type of memory may appear to run correctly because many Amigas have only Chip 
memory. (On all models of the Amiga, the first 512K of memory is Chip memory and in some 


later models, Chip memory may occupy the first one or two megabytes). 


However, once expansion memory has been added to an Amiga (type MEMF_FAST), any 
memory allocations will be made in the expansion memory area by default. Hence, a program 
can run correctly on an unexpanded Amiga which has only Chip memory while crashing on an 
Amiga which has expanded memory. A developer with only Chip memory may fail to notice 


that memory was incorrectly specified. 


Most compilers have options to mark specific data structures or object modules so that they will 


load into Chip RAM. Some older compilers provide the Atom utility for marking object modules. 


If this method is unacceptable, use the AllocMem() call to dynamically allocate Chip memory, 
and copy your data there. 


When making allocations that do not require Chip memory, do not explicitly ask for Fast 
memory. Instead ask for memory type MEMF_PUBLIC or 0L as appropriate. If Fast memory is 


available, you will get it. 


Q Never use software delay loops! Under the multitasking operating system, the time spent in a loop 
can be better used by other tasks. Even ignoring the effect it has on multitasking, timing loops 
are inaccurate and will wait different amounts of time depending on the specific model of Amiga 
computer. The timer.device provides precision timing for use under the multitasking system and 
it works the same on all models of the Amiga. The AmigaDOS Delay() function or the 
graphics.library /WaitTOF() function provide a simple interface for longer delays. The 8520 
I/O chips provide timers for developers who are bypassing the operating system (see the Amiga 


Hardware Reference Manual for more information). 


(J Always obey structure conventions! 


All non-byte fields must be word-aligned. Longwords should be longword-aligned for 


performance. 


All address pointers should be 32 bits (not 24 bits). The upper byte must never be used for data. 


Fields that are not defined to contain particular initial values must be initialized to zero. This 


includes pointer fields. 
All reserved or unused fields must be initialized to zero for future compatibility. 


Data structures to be accessed by the custom chips, public data structures (such as a task control 
block), and structures which must be longword aligned must not be allocated ona 


programs stack. 


Dynamic allocation of structures with AllocMem() provides longword aligned memory of a 
specified type with optional initialization to zero, which is useful in the allocation of 


Structures. 


For 68010/68020/68030/68040 compatibility 


Special care must be taken to be compatible with the entire family of 68000 processors: 


LI Do not use the upper 8 bits of a pointer for storing unrelated information. The 68020, 68030, and 
68040 use all 32 bits for addressing. 


“I Do not use signed variables or signed math for addresses. 


(1 Do not use software delay loops, and do not make assumptions about the order in which 


asynchronous tasks will finish. 


Q The stack frame used for exceptions is different on each member of the 68000 family. The type 
identification in the frame must be checked! In addition, the interrupt autovectors may reside ina 


different location on processors with a VBR register. 


(9 Do not use the MOVE SR, <dest> instruction! This 68000 instruction acts differently on other 
members of the 68000 family. If you want to get a copy of the processor condition codes, use the 


exec.library /GetCC() function. 


1 Do not use the CLR instruction on a hardware register which is triggered by Write access. The 68020 
CLR instruction does a single Write access. The 68000 CLR instruction does a Read access first, 
then a Write access. This can cause a hardware register to be triggered twice. Use MOVE.x #0, 


<address> instead. 


QO Self-modifying code is strongly discouraged. All 68000 family processors have a pre-fetch feature. 
This means the CPU loads instructions ahead of the current program counter. Hence, if your 
code modifies or decrypts itself just ahead of the program counter, the pre-fetched instructions 
may not match the modified instructions. The more advanced processors prefetch more words. 


If self-modifying code must be used, flushing the cache is the safest way to prevent troubles. 


O The 68020, 68030 and 68040 processors all have instruction caches. These caches store recently used 
instructions, but do not monitor writes. After modifying or directly loading instructions, the 


cache must be flushed. See the exec.library /CacheClearU() Autodoc for more details. 


If your code takes over the machine, flushing the cache will be trickier. You can account for the 


current processors, and hope the same techniques will work in the future: 


CACRF ClearI 


ClearICache: 


cic 040: 
CiC ex1Gs 


EQU $0008 ;Bit for clear instruction cache 
;Supervisor mode only. Use only if you have taken 
;over the machine. Read and store the ExecBase 
;processor AttnFlags flags at boot time, call this 
;code only if the "68020 or better" bit is set. 


dc.w S$4E7A,$0002 ;MOVEC CACR,DO 

tst.w dd ;movec does not affect CC’s 
bmi.s cic 040 7A 68040 with enabled cache! 
ori.w #CACRF ClearI,d0 

dc.w $4E7B,$0002 ;MOVEC DO,CACR 

bra.s cic exit 

dc.w S£4b8 ;CPUSHA (IC) 


Hardware programming guidelines 


If you find it necessary to program the hardware directly, then it is your responsibility to write code that 


will work correctly on the various models and configurations of the Amiga. Be sure to properly request 


and gain control of the hardware resources you are manipulating, and be especially careful in the 


following areas: 


O Kickstart 2.0 uses the 8520 Complex Interface Adaptor (CIA) chips differently than 1.3 did. To 


ensure compatibility, you must always ask for CIA access using the cia.resource/AddICRVector() 


and RemICRVector() functions. Do not make assumptions about what the system might be using 


the CIA chips for. If you write directly to the CIA chip registers, do not expect system services 


such as the trackdisk.device to function. If you are leaving the system up, do not read or write to 


the CIA Interrupt Control Registers directly; use the cia.resource/ AbleICRQ, and SetICRQ 


functions. Even if you are taking over the machine, do not assume the initial contents of any of 


the CIA registers or the state of any enabled interrupts. 


J All custom chip registers are Read-only or Write-only. Do not read Write-only registers, and do not 


write to Read-only registers. 


J Never write data to, or interpret data from the unused bits or addresses in the custom chip space. 


To be software-compatible with future chip revisions, all undefined bits must be set to zeros on 


writes, and must be masked out on reads before interpreting the contents of the register. 


QO) Never write past the current end of custom chip space. Custom chips may be extended or enhanced 


to provide additional registers, or to use bits that are currently undefined in existing registers. 


QO Never read, write, or use any currently undefined address ranges or registers. The current and 


future usage of such areas is reserved by Commodore and is subject to change. 


U Never assume that a hardware register will be initialized to any particular value. Different versions 
of the OS may leave registers set to different values. Check the Amiga Hardware Reference 


Manual to ensure that you are setting up all the registers that affect your code. 


Additional assembler development guidelines 


If you are writing in assembly language there are some extra rules to keep in mind in addition to those 


listed above. 


QO Never use the TAS instruction on the Amiga. System DMA can conflict with this instruction’s 


special indivisible read-modify-write cycle. 


O) System functions must be called with register A6 containing the library or device base. Libraries and 
devices assume A6 is valid at the time of any function call. Even if a particular function does not 
currently require its base register, you must provide it for compatibility with future system 


software releases. 


©) Except as noted, system library functions use registers DO, D1, AO, and A1 as scratch registers and 
you must consider their former contents to be lost after a system library call. The contents of all 
other registers will be preserved. System functions that provide a result will return the result 


in DO. 


Q Never depend on processor condition codes after a system call. The caller must test the returned 


value before acting on a condition code. This is usually done with a TST or MOVE instruction. 


Commodore Applications and Technical Support (CATS) 


Commodore maintains a technical support group dedicated to helping developers achieve their goals 
with the Amiga. Currently, technical support programs are available to meet the needs of both smaller, 
independent software developers and larger corporations. Subscriptions to Commodore’s technical 
support publication, Amiga Mail, is available to anyone with an interest in the latest news, Commodore 


software and hardware changes, and tips for developers. 


To request an application for Commodore’s developer support program, or a list of CATS technical 


publications send a self-addressed, stamped, 9" x 12" envelope to: 


CATS-Information 
1200 Wilson Drive 
West Chester, PA 19380-4231 


Error Reports 


In a complex technical manual, errors are often found after publication. When errors in this manual are 
found, they will be corrected in a subsequent printing. Updates will be published in Amiga Mail, 


Commodore's technical support publication. 


Bug reports can be sent to Commodore electronically or by mail. Submitted reports must be clear, 
complete, and concise. Reports must include a telephone number and enough information so that the 


bug can be quickly verified from your report (i.e., please describe the bug and the steps that produced it). 


Amiga Software Engineering Group 
ATTN: BUG REPORTS 
Commodore Business Machines 
1200 Wilson Drive 

West Chester, PA 19380-4231 

USA 


BIX: amiga.com/bug.reports | (Commercial developers) 
amiga.cert/bug.reports (Certified developers) 
amiga.dev/bugs (Others) 


USENET: bugs@commodore.COM or uunet!cbmvax!bugs 
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Library Autodocs 


Most of the Amiga’s operating system is divided into groups of functions called libraries. Libraries reside 
either in the Amiga’s ROM or on disk. Once a library is opened, any of its functions can be called. For 
example, if you want to call the Read() function to read data from disk you must first open the DOS 
library. In general, to do anything useful on the Amiga you must first open a library. 


This section contains summaries for all the functions in all of the libraries that are built into the Amiga’s 
operating system software. These summaries have been automatically extracted from the original source 


code and are called Autodocs (for automatic documentation). 


The Autodoc files are organized alphabetically by library, one document for each function call. For 
additional tutorial information on each of the libraries and more details about the Amiga’s library 
mechanism refer to the Amiga ROM Kernel Reference Manual: Libraries. Only a brief introduction is given 
here. The exec.library is the system’s master library and is always open. One Exec function, 


OpenLibrary(), is used to open all other libraries. 


Usage is as follows: 
struct LibBase *LibBase; /* Global: declare this above main() */ 
LibBase = OpenLibrary("library.name", version) ; 


if ('LibBase) { /* Library did not open, so exit */ } 
else { /* Library opened, use functions */ } 


where: 


LibBase isa pointer to the library base. This is a global variable used by the system to handle 
function calls. In the code above, if the library cannot open for some reason LibBase will equal 0. 
The variable name for a library base pointer is different for each library. Refer to the list below 


for the appropriate name. 
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library.name isa string that describes the name of the library you wish to open. The list of 


library names is given below. 


version should be set to the earliest acceptable library version. A value of 0 matches any 
version. A value of 33 means you require at least version 33 or a later version of the library. If 


you specify a higher version number than is present in the system, OpenLibrary() will fail (return 


0). For the system libraries, the following table applies: 





Many of the libraries and functions documented in this manual are available in all versions of the 
Amiga operating system. Others are completely new and cannot be used unless you have 


successfully opened the appropriate version of the library. 


The functions which are new for V36 or V37 are marked with (V36) or (V37) in the NAME 
line of the function Autodoc. These new functions are not available in earlier versions of the 
Amiga libraries. If your code calls any system function that is marked with (V36) or (V37) 


then use a matching version number (36, 37, or higher) when opening the library. 


Exit gracefully and informatively if the required library version is not available. Please note that 


since V34 Kickstart is nearly identical to V33, it is generally not wise to require V34. 
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The OpenLibrary() function returns the address of the library base, which you must assign to a specific 
global system variable. The list of global system variable names for each library is given below (case is 
important.) The system uses the library base to access the functions of the library. If the library cannot 
open for some reason, the OpenLibrary() function returns zero. Library bases represent a midpoint in the 


library. Below the base are the function vectors, above the base is the library data area: 


Data area 


Function 1 
Function 2 


<¢—————-Higher address 






Library Base Pointer 





Function n 
+—————- Lower address 


The names of the libraries that are currently part of the Amiga system software and their associated 
library base pointer names are: 





All Amiga libraries accept parameters in registers, and return the result in data register DO. All routines 
return a full 32 bit longword unless noted otherwise in the function Autodoc. This allows programs and 
functions that are written in assembler to communicate quickly. It also eliminates the dependence on the 
stack frame conventions of any particular language. Some C language compilers for the Amiga can 
generate parameters directly into registers, others translate any Amiga library call into a stub routine that 
moves parameters from the stack to registers. See the discussion of “amiga.lib” in the Linker Libraries 


section of this book for more details. 


Complete examples of how to open and close a library follow. 


* 


A complete ready-to-compile example of library use. 
The library is opened, checked, used and closed. 

See the intuition.library document for a description 
of what the DisplayBeep() function does. 


+ + + F FON 


™ 


struct Library *OpenLibrary() ; /* declare return type */ 
struct IntuitionBase *IntuitionBase; /* get storage for base */ 


void main () 
{ 
IntuitionBase=(struct IntuitionBase *) 
OpenLibrary ("intuition.library", 33L) ; 


if (!IntuitionBase) /* check if it actually opened */ 
exit (20); /* a return value of 20 indicates failure */ 
DisplayBeep (OL) ; /* use the library function */ 


CloseLibrary (IntuitionBase) ; 
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* 
* A complete ready-to-assemble example of library use. The intuition 
* library is opened, checked, used, and closed. See the intuition 
* document for a description of what the DisplayBeep() function does. 
* 
* When calling an Amiga library, the base pointer *must* be in 
* A6... the library is free to depend on this. Registers DO,D1,A0 
* and Al may be destroyed by the library, all others will be preserved. 
* 
_AbsExecBase EQU 4 ;Where exec’s library base is 
XREF _LVOOpenLibrary ;Offset from base for OpenLibrary 
XREF _LVOCloseLibrary , 
XREF _LVODisplayBeep yr 
move.l —_AbsExecBase, a6 ;Move exec.library base to a6 
lea.l IntuiName (pc),al ;Pointer to "intuition.library" 
moveq #33,d0 ; Version 
jsxr _LVOOpenLibrary (a6) ;Call exec’s OpenLibrary() 
Sts do 
bne.s open ok 
moveq #20,d0 ;Set failure code 
rts ;Failed exit 
open ok move.l1 d0,aé ;Put IntuitionBase in a6. 
suba.l a0,a0 ;Load zero into a0 
JSxr _LVODisplayBeep (a6) ;Call intuition’s DisplayBeep () 
move.l a6,al ;Put IntuitionBase into al 
move.l1 —AbsExecBase, a6 
jsxr _LVOCloseLibrary(a6) ;Call exec’s CloseLibrary () 
moveq #0,da0 ;Set return code 
rts 
IntuiName: dc.b ’intuition.library’,0O 
END 
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Device Autodocs 


This section contains summaries for the device calls that are built into the Amiga’s operating system 
software. These summaries have been automatically extracted from the system source code and are 


called Autodocs. 


Devices are based on the library concept described in the last section. But unlike libraries, devices use a 
standard command interface. Once you have learned how to use one Amiga device, it’s easy to learn the 


others. 


An Amiga device is a hardware-independent software module for interacting with a physical I/O device 
(such as a disk drive or serial port). Devices typically have their own independent tasks that can perform 


asynchronous operations even while the task that called them is busy doing something else. 


For a more detailed introduction to the Amiga device concept refer to the Amiga ROM Kernel Reference 
Manual: Devices. Only a brief introduction is given here. The table below shows the names of all the 


devices that are currently part of the Amiga system software. 
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Devices are more complex to use than libraries. Opening a device requires: 


“J A message port structure (struct MsgPort). This structure is used for inter-task communication. 
Ports may be created with the amiga.lib/CreatePort() function. See the section on Linker 


Libraries for more information on CreatePort(). 


UW An I/O Request structure (struct IORequest or one of its extended forms). This special structure, 
plus any extensions, is your sole source of communication with the device. Commands and data 


(or data pointers) are placed in this structure and sent off to the device. 


The format of the basic IORequest structure is defined in the exec/io.h listing (see the section on 
Include Files). Some devices use a special extended version of the IORequest structure. If so, the 
extended IORequest is defined in the include file for the particular device that uses it. An 
IORequest can be created with the amiga.lib/CreateExtIO() function. See the Linker Libraries 


section for more information on CreateExtIO(). 


1) The name of the device for the Exec OpenDevice() call. The names of Amiga devices are shown in 


the table on page 461. 


Opening the device initializes the IORequest for use. The request will always be associated with the 
device that initialized it so you cannot use it with other devices. Once the device is opened, you can send 
commands to it. Commands are placed in the io Command field of the IORequest, then the request is sent 


to the device. There are two primary options for sending the request: 


DolOQ - An Exec call that does the I/O and returns only after it has finished (this is synchronous I/O). 


This is the easiest option to use. 


SendIO(Q) - An Exec call that starts the I/O, but returns immediately (this is asynchronous I/O). The 
device will complete its job while your calling task continues to run. Before reusing the 
IORequest, you must wait for the I/O to finish. You can send multiple requests to a device 
and the requests will queue up. However, you must use separate IORequest structures for 


multiple requests. 


When you have finished using a device, a call to CloseDevice() completes the transaction. For those 
programs using asynchronous I/O, any outstanding requests must have already been completed. This 


can be done by a WaitIO0, or by forcing termination with an AbortIO()/WaitIO( pair. 
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/* 

* A complete example of using the trackdisk.device. 
* This moves the heads from track 0 to 79 and back. 
x 

af 

#include "exec/types.h" 

#include "devices/trackdisk.h" 

#include "dos/dos.h" 


struct MsgPort *trackport=NULL; /* Storage for pointers */ 
struct IOExtTD *trackIO=NULL; /* An extended version of struct IORequest */ 
short openerror=NULL; fe £ lag -*/ 


void cleanexit (returncode) 
int returncode; 


{ 


printf ("openerror =%ld\n" ,openerror) ; 

printf ("trackIO =$%lx\n",trackI0O) ; 

printf ("trackport =$%lx\n",trackport); 
( 


Pprinti ("10 Exror =tld\n" -,;tracklO->10td Req.io Error); 


a 


if (!openerror) CloseDevice (trackI0O) 
if (trackI0O) DeleteExtIO(trackI0O); 
if(trackport) DeletePort(trackport); 


exit (returncode) ; 


void main() 
{ 
trackport=(struct MsgPort *)CreatePort (OL,O0L); 
if (!trackport) 
cleanexit (RETURN FAIL); 
trackIO=(struct IOExtTD *) 
CreateExtIO(trackport, (long)sizeof (struct IOExtTD)); 
if(!trackIO) 
cleanexit (RETURN FAIL+1); 
if (openerror=OpenDevice ("trackdisk.device",0OL,trackI0O, OL) ) 
cleanexit (RETURN FAIL+2); 


trackIO->iotd Req.io Command=TD_ SEEK; /* trackdisk command */ 


trackIO->iotd Req.io Offset =OL-; /*®: Ouver track’ */ 
printf ("Track O\n"); 

DolO(trackIO); 

tracklO=srotd Reqvio- Oiisel =J96litZolZh; 7. SONGS (Crack -*/ 
prinelL( irack 79\n); 

DolO(trackI0O); 

trackIO->iotd Req.io Offset =O0L; /® OULer. Crack 7 

printhL ("Track O\n"); 

DolO(trackIO); 

treckiOnw>ieud Rég.10 Ofiset: =19s Is gr oi 2ke /*. 2Oner Track sy 
printf ("Track 79\n"); 

DolO(trackIO); 


cleanexit (RETURN OK); 
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/* sTeqToep ut Aueuysn{Cpe tw x/ o = Cpetw<-gior 
/» sde3s $GI-W UT queuysnfpe Eg x/ 0 = Cpeea<-gior 
/» sde 4s %ST-W Ut queuqsntpe Za y/ 0 = €peza<-ayor 
/» 8de3s $ST-W Ut Queugsnfpe Ta x/ o = Cpeta<-quor 
/* (spuze Ut) uoTjeqinqied oF x/ Ze = qanqzedoa<-gyo1 
/%* TOYSF UoTsznoxse OW »/ O = WSETSsnyAUueCga<-qHol 
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= sy qnou<-gior 






/* bezy Bbuttdues otpny x/ 007zzZ = 
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Resource Autodocs 


This section contains summaries for the Amiga’s system resource routines. Resources contain low-level 
hardware control functions that arbitrate control of chip registers, interrupts and other low-level 
hardware. Resources should not be used unless your program has special, high-performance 


requirements that cannot be met through the conventional function interface provided by the Amiga’s 


library and device functions. 





There are currently seven standard resources in the Amiga system: 


1 battclock.resource grants access to the Amiga’s clock chip. Not all Amiga’s have the clock chip, so 


use this with care. 


1 battmem.resource grants access to non-volatile RAM. Not all Amiga’s have non-volatile RAM, so 


use this with care. 


UO cia.resource grants access to specific bits and individual interrupts for each of the 8520 CIA chips 
(Complex Interface Adapters). There are two cia resources: ciaa.resource and ciab.resource, 


which correspond to the odd and even 8520 CIA chips. 


QO) disk.resource grants temporary exclusive access to the disk hardware (one for each of the four 


possible disk/MFM units). 


LI FileSystem.resource provides a list of filesystems available for use. 
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_J misc.resource grants exclusive access to functional blocks of chip registers. At this time definitions 
have been made for the serial and parallel hardware. When a task owns the misc.resource for a 


port, it has control over that port’s associated hardware. 


I potgo.resource manages the bits of the POTGO (write-only) and POTINP (read-only) registers. 
These custom chip registers control the proportional input pins on the game controller ports. The 
pins may also be used for digital input and output. Intuition uses port 1 for reading the right and 


(optional) middle mouse buttons. 


See the Amiga Hardware Reference Manual for more information on the actual hardware that each resource 


controls. This section covers only the arbitration provided in the Amiga’s multitasking system. 





Assembly language fragment that grabs one of the two groups of serial 
port bits (using the misc.resource). If it is successful at obtaining 
the resource, it will hang on to it forever, and never return. 


This example must be linked with amiga.lib 


+ + + + HF 


INCLUDE "exec/types.i" 
INCLUDE "resources/misc.i" 


_AbsExecBase equ 4 


JSRLIB MACRO 
XREF SEVON 
JSR _LVO\1 (A6) 
ENDM 


move.l AbsExecBase,a6 

lea.l MiscName (pc),al 

JSRLIB OpenResource 

stud. “dv 

beg.s nO open 

move.l d0,a6 j;resource base in A6 


; We now have a pointer to a resource. 
, Call one of its library-like vectors. 


move.l #MR_SERIALPORT,d0 ;We want these bits 

lea.l MyName(pc),al ;This is our name 

jJSr MR ALLOCMISCRESOURCE (a6) 

tSt.1 -dQ 

bine ss. NO. get ;Someone else got it 
; We just stole the serial port registers. Wait forever. 


,; Nobody else can use the serial port, including the serial.device! 
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move.l AbsExecBase, a6 


move.l #0,d0 ;Wait for nothing (forever) 
JSRLIB Wait 
NO.get ;Someone else has it, exit! 
no open move.l #21,d0 
rts 
MiscName dc.b ‘’misc.resource’,0O 
MyName de. ‘Serial Port hog’,0 
END 


/* An example of using the potgo.resource to read pins 9 and 5 of 
* port 1 (the non-mouse port). This bypasses the gameport.device. 
* When the right button on a mouse plugged into port 1 is pressed, 
* the read value will change. Use of port 0 (mouse) is unaffected. 
4 

#include “exec/types.h" 

#include "libraries/dos.h" 


APTR PotgoBase; 
ULONG potbits; 
UWORD value; 


#define UNLESS(x) if (! (x)) 
#define UNTIL(x) while(!(x)) 
#define OUTRY 1L<<15 
#define DATRY 1L<<14 
#define OUTRX 1L<<13 
#define DATRX 1L<<12 
/* Note: Aztec C prototypes use an extra version */ 

void main() /* argument in the OpenResource() function * / 
{ 

UNLESS (PotgoBase= (APTR) OpenResource ("potgo.resource") ) 

exit (RETURN FAIL); 
printf ("PotgoBase is at $%1x\n",PotgoBase) ; 


potbits=AllocPotBits (OUTRY |DATRY |OUTRX|DATRX) ; 
/* Get the bits for the right and middle mouse buttons 
on the alternate mouse port. */ 


if(potbits != (OUTRY|DATRY|OUTRX |DATRX) ) 
{ 
printf("Pot bits are already allocated! %1lx\n",potbits); 
FreePotBits (potbits) ; 
exit (RETURN FAIL+1); 


} 


WritePotgo (OxFFFFFFFFL,potbits); 
/* Set all ones in the register (masked by potbits) */ 


UNTIL(SIGBREAKF CTRL C & SetSignal (OL, OL) ) 
/* until CTRL-C is pressed */ 
{ 
value=* (UWORD *)OxOODFFO16; 
/* Read word at SDFFO16 */ 
printf ("POTINP = S$%1lx\n",value & potbits); 
/* Show what was read (restricted to our allocated bits) */ 
} 
FreePotBits(potbits); 
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Linker library Autodocs 


This section contains Autodoc summaries for the amiga.lib and debug.lib linker libraries, and reference 
source code listings for Exec support functions in amiga.lib. Unlike the libraries described in the first 
section of this book, the linker libraries are not shared run-time libraries. Instead, they are concatenated 
Amiga format object modules which are linked with your code as library files. The linker scans specified 


library files and inserts a copy of each referenced library function into your program code. 
The linker libraries described here are debug.lib and amiga.lib: 


() amiga.lib is the main Amiga scanned linker library, generally linked with every program for 


the Amiga. The major components of amiga.lib are: 


stubs - Individual interface stubs for each Amiga ROM routine that enable stack-based C 


compilers to call register-based Amiga ROM routines. 


offsets - The negative Library Vector Offset (_LVO) for each Amiga function. Assembly 


language program should link with amiga.lib to resolve their _LVO references. 


exec_support - C functions that simplify many Exec procedures such as the creation and 
deletion of tasks, ports, and I/O request structures. Source code is provided for these 


functions. 


clib - C support functions including pseudo-random number generation and a limited set of file 


and stdio functions designed to work directly with AmigaDOS file handles. 


other - Miscellaneous handy functions, callable from any language. 
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MY debug.lib contains stdio-like functions for communicating with a serial terminal connected to the 
Amiga via its built-in serial port. Typically, this terminal will be a 9600 baud, 8 data bits, one 
stop bit connection to an external terminal or an Amiga running a terminal package. The 
debug. lib functions allow you to output messages and prompt for input, even from within low- 
level task or interrupt code, without disturbing the Amiga’s display and or current state (other 
than the state of the serial hardware itself). No matter how badly the system may have crashed, 


these functions can usually get a message out. 


A similar debugging library currently called ddebug.lib is available for sending debugging 
output to the parallel port. This is useful for debugging serial applications. Ddebug.lib is not 
documented here. It contains functions similar to debug.lib but with names starting with ‘d’ 


instead of ‘k’. 


Shown below is a simple example of using the linker libraries from assembly language. 


Demonstrates assembler use of the compiled C exec support routines 
(CreatePort, etc.) in amiga.lib, and also the use of amiga.lib 
csupport functions such as printf for simple formatted output and 
debugging. Creates a port, outputs its address, and deletes the port. 
Comments show the functions as they would be called from C. 


LINK INSTRUCTIONS: Alink with Astartup.obj ... LIBRARY amiga.lib 

Astartup sets up DOSBase and the stdout needed for amiga.lib printf. 

If you do not link with Astartup.obj, you must add the following 
variables, XDEF them, and initialize them as commented: 

DC.L _DOSBase Q ;needs base returned from OpenLibrary of dos.library 
DCs: stdout QO ;needs an AmigaDOS file handle from a dos Open call 
DC.L SysBase O ;needs the address stored at location 4 


+ + + + + ££ * FF Fe + HF 


INCLUDE "“exec/types.i" 
INCLUDE "exec/io.i™ 
INCLUDE “libraries/dos,i" 


Koma Imported labels: C interface Amiga.lib routines 
AREER .iCreavePore 
AREF  DeletePort 
AREF 2 OFanwTe 


k*---— Exported labels: Where Astartup.obj JSR’s to our code 
XDEF — main 


CODE 
ruse Startup code ( main + link with Astartup.ob}j) 


_main: 
movem. 1 d2-d7//a2-a6,-(sp) ;Save registers 
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Ra Exec Support function: msgPort = CreatePort (name, pri) 
move.1 #0,-(sSp) ;push priority O on stack as long 
pea portname ;push addr of null-termed portname 
jsr -CreavlePort (Cai) Createrort 
addq.1l #8,Sp ;add 4 to stack for each long pushed 
jsxr mydebug0 ;rtn to print dO (preserves dQ) 
tst.-L do ;test result 
beq.s failure ;if zero, CreatePort failed 
ee Exec Support function: DeletePort (port) 
move.l G0 7=(Sp) ;else push dO (now our msgPort) 
jsr _velLelerort ;call DeletePort 
addq.l #4,Sp ;add 4 to stack for pushed long 
move.l #RETURN OK, d0 ;set up success return code 
bra.s endcode ;and skip to exit code 
la Failure to CreatePort branches here 
failure: 
move.L #RETURN FAIL, dO ;set up failure return code 
endcode: 
movem. 1 (sp) +,d2-d7/a2-a6 ;Restore registers 
rts ;rts with dO = return code 
Re mydebugO - Subroutine uses Amiga.lib printf to print the contents 
x of dO. Preserves all registers. 
mydebug0: 
movem. 1 adO0-d7/a0-a6,-(sp) ;save registers 
lis © Support. function printf (): here -printr("stlx\n",;contéents of dO) 
* Note that the fstrl DC.B below specifies ’\n’ and null as 10,0 
move.1l d0,- (sp) ;push dO on the stack 
pea fstr spush addr of format string 
jsr printf ;call printf 
addq.l #8,Sp ;add 4 to stack for each long 
movem. 1 (sp)+,d0-d7/a0-a6 ;restore saved registers 
rus PLS 
DATA 
portname DC.B “sample msgport’,0 
fstrl DCB “StL ¢ LOy0 
END 


; Example C Callable function that adds two numbers. From C, the 
; call would look like this: 
q result=AddThemUp (first,second); 


XDEF | AddThemUp ;Make an External Definition 
_AddThemUp 

move.1l 4(sp),D0O ;Get FIRST number 

move.l 8(sp),D1 ;Get SECOND number 

ada. |* “Dake, DO ;Add them 

rts ;Return result (which is in DO) 
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C language include files 


This section contains the C-language include files from the Amiga operating system source code. These 
include files define the data structures and constants used by the system software. Whenever the system 
requires a certain structure or constant, it will be defined in an include file. These include files are 
organized ona functional basis. For example, files pertinent to the graphics library are listed under 


graphics/filename.h. 


This section is for easy reference only. Similar include files generally come on disk with whatever C 


compiler you may choose to use with the Amiga. It is impotant to keep in mind that the include files that 


come with the compiler may not be an exact match to the files listed here. 





Listed below is a simple example of a C program which uses the system header file dos.h. 


[x 

* A quick example of using a C language include file. The constant 
* "ID KICKSTART DISK" is not defined in this example; the value 

* is pulled from the "libraries/dos.h" include file. 


wi 


#include “libraries/dos.h" 

void main() 

{ 
printf ("ID KICKSTART DISK equals six\n"; ID KICKSTART DISK) ; 
exit (RETURN OK) ; 
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ce H% 
UOTReOTUNUMIOD SsoTAep TOF pesn saranjonayjs shHessap “x sqdnizejut ezemqyos ¥ ezempzey Aq pesn saanqonazaqys YAOeQqTTeD *% 
*% *¥ 
$ OT/S0/06 -93ed$ ¥% $ OT/S0/06 :e3eA$ *x 
$ P°9E :UOTSTASYS 4x $ p'9E iuCTsTADdYSs xx 
$ pO’? :eseeTeus ax $ pO°Z :eseaTous ax 
$ Y°Ot/oexe ‘toweusTta$ xx § y'sqdnazequt/oexe ‘:euweueTta$ 
Secs x/ 
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/* H SLSIT D3Xa x/ 


( (asti1bsyw du<-(x)¥9) (x @PON AONnzAS) == (peTGTteL UT 3st bsp du<-(x)) ) 
\ (x) Aqdurqgqrogbsysr 


( (Xx) (¥ @poN Qonazqs) == (pezaTter yt<-(x)) ) 
\ (x) Aqdurgqstisr 


:(,u\Aqdue st 4st7,,) yqutad ( (3stt)Aqdug3stIsrI )stT 
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$ 6T/20/T6 :e3ea$ 

$ 6°9€ :UOCTSTASYS 

$ pO°? :eseeTous 

$ U'S3STT/oexe ‘:oureueTtys 


H_SLSIT O@Xa 
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souTFJop# 
/* 
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/* 
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*/ 
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*/ 
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qupuedo YT 
umg YT 
butz4spr_ut 
UOTSTASY UT 
uOoTSI@A UT 
ezTssod UT 


qupuedo qtt 
umg TT 
HutI3sPplI_ att 
UOTSTASY_ATT 
UOTSIeA QTT 
@ZTSSOd ATT 


SZTSHeN ATT eZTSHen YT 
ped_att ped_ut 
sbelta Atl sHbeta ut 


®PON ATI SPpON UT 


JTpus# 


ouTyepH 
euTJepH 
eauTyopH 
ouTJop# 
euTyep# 
SuTyJopH 
eu, sopH 
euTyJepH 
euTyep# 
euTyepH 


/+ Aatttaqtqzeduoy Azezoduey, ,/ 


/x ebundxs pedkejtep ,/ (€>>T) dXATAC Jal 

/» UNS OF TYCO pTNoys eM FT os x/ (Z>>T) GasoWns dat 
/x QTT 944 pebueyo ysnf oaey om y/ (I>>T) GHONWHO dart 
/x butummsydeyo ATQuezInS ere om y/ (O>>T) ONIWWOAS AIT 


euTJeopH 
euTyJepH 
euTyepH 


eautyep# 
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if 


/» suedo Auetinod Jo zequmu ,/ /quguedg qTT Caomoa 
/x JTPSAT uMsyYooyd ayQ x/ ‘ums QtT ONOTN 
/~ UOTAISOTFTQUSPT TIOSW x/ ‘HutzrASPpI_ATtT aLdw 
/x ZOUTU y/ /UOTSTASY_GQTT  dyomn 
/+ zoCeu ,/ /UOTSIeA GTT dyomn 
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‘ped qtr azaao 
‘sbeta Qtt aLAaN 
-SPON QTT SpOoN WoONIzRs 
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/x S@e0TNOsSSeY SUIOS puke sedTAeq TOF pesn ostw x/ 
[xr r rrr rrr ermnjonaAS eseg Azeaqrty ------ x/ 
/x wotsuedxe einqny oJ x/ (yc-) ONNALXE_AII eutyepy¥ 
(8T-) FONNdXA AIT eutyop# 
(ZT-) ASOIO_ GIT eutzop# 
(9-) NadO GIT eutyep# 
[ rrr oe suotqoung prepueqjs ------ x/ 
mn _ (agqaaso_art) GLSNON_ GIT eutzep# 
((€AZISLOSA ALTxdSANaSHTa AII)-aSWa AIT) JACUISN AIT eutzyop# 
(AZISLOGA AITI-) aASWa_dII sutyop}# 
/x SAOYSA F YSATJF SYQR seaTSsSeT dexyY ,/ v CaAUASTA_AII eutyep4y 
/x seqkq 9 sexeq Arque AzexrqtyT yorg »/ 9 AZISLOGA ALI eutyzop# 
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SeTIeIqi,T oexg Sutsn zo Hutrqesez> useym esn AOJ suotyAtutseg 
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SsUuTJoPH 


H SHUIMWURIT OAXA Jopuzt# 
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} 38} TWe_ AONnTA8 
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12428 OOO OOOO ORO OO OOOO OO Ooo. 2S FTUSN xxx nne/ 


Ippy_neu-uq eu Ippy_eu eutyep} 
sbey neu‘un eu sbey_ eu sutyep}# 
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/x wotbez Azoweuw styqq so yqAbueT eqQ ,/ ‘qqbuey ou SNOTO 
_ fag ou { 
/x wuotfex Azouwew styqy Jo sserzppe ayQ ,/ /appw_neu ULaw 
/x Suewertnbexr we~_ooTTwW 249 x/ ‘sbay now ONOTO 

} woftun 

} AzqugueW_ 4ONTAs 
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/x saqkq vary FO TSEqumuU TeRI0CF ,/ feerq qa SNOTN 
/x T+punoq Axouweu zeddn ,/ jzeddq qu ULGw 
/* punoq Axoureur TeMOT y/ ‘zemoT Yu ULaw 
/* uothez eery 4saty x/ /38ATA Wy YunyoOuweW AoONIzAs 
/x uoTbez sty JO soTAstTTeqoereyo »/ iseqnqtiz3aaqw yr qaYoma 
‘epoN YW epoN  yonAzAs 

} zepeequeRR WoONnzQs 


[| RRA OR ROO ORO OOO OR OOOO opp TEPPSHUSWN xx yeaa / 


/x ezts e3Aq yunyo x/ _  fseqiq ou SOnotTOA 
/x YANnYD 4xevu Of AeQuTod ,/ ‘/AxeN OUyY YuNQoOuweW WAoONTAS 
} NunyoueW .ONnTQs 


2 ae | RRA OOOO OOOO OOO OUR YUNG OUSN xx pax / 
/x H XYOWEN OFXA «/ JTpus# 


(T-aZISMOOTA WAN) MSWAAOOTA WEN euTyep#H /x H SHCON OFX x/ Ftpus# 
18 AZISHOOTE WAN SUuTZJSpH uw Sepou/oexse,, espnTouTt# 
- H SAAON DEXA Fopuzst# 
/x Azowew JO eztTs TeRIOR uAN_er :wWeMTTeAW x/ (6T>>IT) TWLOL IWAN euTyeop#H 
(8T>>IT) ASUHARY_AWAW euTyeEpH /x 
(LI>>IT) LSADSUWI_AWAN euTzJep}H pearesay squbty TIw Hx 
(9T>>IT) UWAIO ANAN euTJep#H ‘our ‘eb tuy-ezopoumiod O66T ‘686T ‘S86T LEG6T ‘986T S86T FuUbtAAdOD (dD) ¥x 
¥% 
/x sseaippe Fo s3tq PZ UTYQTM AzoueU SsTQqeywWd +«/ (6>>‘IT) WNGLIa?Z_dWaN euTJepH uweysks uotjeootte Azouweu aeyq Aq pesn seinjonazys pue suotytuTyeqd va 


(8>>1T) 'IWOOT_AWaN euTzep}# 4% 

(@>>1T) GLSVd_AWAW oUTJOpP# $ 11/90/06 :e3ed$ 4% 

(I>>IT) dIHD_AWAW euTzyop}# $ IT°9€ iuoTSsTAeUs yi 

(O>>IT) OIITdNd_dAWaW $ pO'Z :eseeTeus 4% 

/x Op Tt Azourwsu Jo odAQ Auy x/ (IO) ANW JWaW $ y Azousu/oexe ‘ioeueueT Tas 4% 
a/ 

H_ AMOWAN_OAXA PUTJeEpF 
H AUOWAW OAXA Fepuzst# 
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/~x @Zeq WOT uMop yxTOM sedAQ epou resp MASON IN 
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St SOIHdWUD_LN euTsZepHe £9 


LT WaWHOIM_IN euTyep# 729 

9T GZCONLOOd IN PUTFepH 9 

/x sezoydeues [eubts ,/ ST WASTWNDIS_IN 2uTsJep# 09 

vT WTAOHAWNAS_IN eUTJep# 6g 

/x sseo0zg soaebtuy ,/ ET SSHO00Ud_IN PUTFJop# BG] 

ZT INO4J_IN ®Utzep# LS 

/x sqturqgzos Aq pesn Betz Teurejur ,/ TT LNILIOS_LIN eutzep# 9¢ 
OT AUOWSW_ LIN euTsep# Gg 


AUWUAIT_IN SUTJOPH FG 
AOUNOSTA_IN eutzepH# EG 
OSWATdaa_IN eutsyep# 7G 

OSWATA_ IN 2PUuTzJoepH TS 

GOVWSSAW_IN euTzep# OG 

LUOdDSW_IN ®UTJeP#H 6F 

AOLIATG_IN eutzep#e BP 

LdNadaaLNI_IN eutzep#e LP 

USWL_IN SUtTyJep#e OF 

= NMONMNO LN eutyeop# SP 
Rennes WdAL NI rox sadAy epon ----- 


/x pettdez useq sey ehessoy ,/ 


/x Sutpued ATAuezaznod seHesseu saqjeotpul ,»/ 


/x XS DEX” x/ 


OANOM HN WOM @®O 





_ "pesn ysaty eze Avyqy weumM yx ZP 
edkAqj e ubtsse TTT SO ®4uL “NMONYNO IN edAQ eaeq prnoys ‘()esneDd 4qATM posn xx IP 
seanqonays qadnazequt ezeaqgos pue ‘sqsenbeyol peztrtetatut ATMAN :2e370N xx OF 


x/ 


Si “{ 
/peid_UTW, eponutW 4oONnzAs GE 

:DONnS UTU,y, ePoONUTW AonzAs PE 

} SPpONUTW 2ONAAS Ef 

/x ®TQTssod BHbutYoeyo edAQ ou -- spou Teuyutu ,/ 








/x peubtTe pIOM :330N »/ 
/x pe zeutuzsZ T{Inu ‘Hutz4s qI x/ /SUeN UT» zeyo 6Z 

/x Burqzos zozy ‘AqAtxrotx7d x/ -Tid UT aALAd A 

_‘oedAL ul aLzAaa LZ 

/x (xossenepertd) snotaaezd oj zequTog ,/ -Peid_UTx SPpON  3on745 9Z 
/x (ZOsseD0NS) JxeU OF AeQZUTO_, ,/ -DONS UTx SPOON WonxzrAS Gc 

} SPOON ROnIzAASs 


/* 
SPON © YATM S4TE4S ASTI © UT Tequeu YyoRyY ‘“ernqoNrAs PPON ASTI x TZ 
*/ 





/x H SUAAL OAXA x/ FTPuoH 
.q7sedXq/oexe, epntout# 9T 


H S@dAL OUXA JOPUFTH GT 


/* 
peazesey sqyhtu Ttw xx CT 
"Duy ‘ebtuy-ertopoumoDd 686T'‘S86T ‘LE6T’986T‘S86T 3uUBtTAAdOD (5D) xx TT 





xx OT 

“szxetyJtjuept edAQq apon F seponNn *% 6 
%¥ 8 

$ 60/TO/T6 -238d$ ¥% L 

$ TT 9€ sUOTSTADdYS *% 9 

$ pO°? -eseoTSOUS *¥ S 

$ Y'sepou/oexs ‘eureueTTta$ *% v 

a 1 x/ € 

H_SHdON_ODaXA eutTzyop}# c 

H SHGON O4XA Fepust# OT 
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y'sopnjou| 


/x H LNAGISHY OAXH x/ Jtpuce# 


T ZaWLsaqiod MLY euTsepF 
0 UAAIN ML euTzepH 
/x € NAHM WL SuTFopHF x/ 
/* (@7@TOSQO) :AATTTQTWedUIOD x/ 


(O>>T) 
(I>>T) 
(Z>>T) 
(L>>T) 


LUWLSAIOO dLd eutzop}# 
UMSVIZIONIS ALY eutzyep¥ 
7 SOCUILIW_ALY euTyop}# 
f/x Panqjonazys eqjep of squtTod ytur 42 ,/ LINIOLAY dlw sutyopF 


/* BOT{AONAASUT ,TWOATII. 00089 PUL x/ OAWPXO CUOMHDLWA OLY ouTsJopH 


ao 
/x ®pod 3TUT 03 requtTod ,/ Atul 3% uLaw 
/x 5utzrAs uotyeotstjuept oj requtod y/ ‘/butzasprl_3ay xzeYD 
/x eweUu espou Of AeRAUTOd ,/ ‘ouen 4Xy eyo 
/x Aqtzotad wuotqeztTerqrur »/ !‘tiaq_32 WAG 
(XXXXXX LN) @eTnpow zo edAQ ,/ ‘edAL 32 aLAGOA 
zequmu UOTSI<A vsseeTor ,/ JUOTSIZA 32I ALAGO 
sHejTy 5eq snotzea ,/ ‘sBbeta 232 aLAGO 
ueos enutqUuoD Of sserppe ,/ ‘dtyspuq 42 ULaw 
eaoqe ey OF TeqAuTod ,/ ‘He_yo ren 4Ar»y Queptsey jonaz4s 
/* (IWDATII) WO YoReU OF PIOM y/ /prOMYOAeW 32 TAOMO 

} QUueptsey AonzyAs 


/x H SHAAL OAXA «/ JTpusz 
uq" sedAQ/dexe,, epntTout# 


H SA€dAL DEXA FoOpusyt# 


/* 

peazesoy sqqhta TIw 4% 

"Duy ‘ebtuy-ezropoumoD 6861 ‘886T ‘LB6T‘986T S86T 34HbTZAdOD (5) *% 
HK 

"FynAs H5eLWou/ jueptsey *% 
4% 

$ TO/TT/06 :e3ed$ *% 

$ 8°9E :uoTSsTASYsS *% 

$ PO’? :eseeTeus ax 

$§ 4° AUeptser/oexe ‘ouweueTtas xx 
2s a x/ 

H_LNACISHY OAXA SuTJop}H 

H LNACISHY OFXA Fopuzst# 


SS[Npou spood aeztTetytut pue Azxtjuept of pesp 


y"jJUSpPISal/DeXxa 


ANANPENUOE ODA 


/x H SLYOd DAXT x/ JTpusz# 


/« (qQ6ueT eqQ UT eanqQONzAs ,/ 
/x ebessay ey JO azTts ayy epntout) ,/ = 
/x se qhq ut ‘yqbuet ebessou [e}094 »/ _ ‘yq6ue7 um dWaomMn 
/x 310d Ajtdez ehessou ,/ ‘qrzogqA{dey um, AToGHsw yonazQAs 
‘aponN WU epoN yoONIAAS 
} eBessex_ qonazQAs 


[AARNE OR A I RO RE ROR OR OR ROR ROR ROR IO ROE aBbesson ere se o/ 


= _ /x Teatrzze exzoublT ,/ 

/x x8eL51Ts du/qur3yyzos du ut qurazos Teubts ,/ 
/+ x8eLbts dur ut yseq Teubts »/ IWNDIS Wd eutyep}# 

/x ASCH */ NOILOW dd eUuTzFOpH 

/x (Bswang) suotqoe Teatazrze 4r0q :sHhetq du ,/ 


AUONDI_ Wd eutyep# 
LNILAOS Wd eutzep# 


/x SETIV x/ xseLbts du jurqzog du eutyzep} 


/* 4STT pexutT ebessou ,/ 
/x PeTTeubts eq 03 30eLqo ,/ 
/* zequmu 3tq Teubts ,/ 


‘ast 7Bsw du jst y  3onz4s 
‘yseLbts duty,  ptoa 
‘qatabts du aLxAan 
‘sHheta dur aLxaoa 
Japon dur espoN WoONnIAs 

} yrogbsyW Qonz4s 


[RRO OR OOOO OOOO OOOO OOOO Ope QIOUBSH axa nnx/ 


/x H SUSWL DFXA x/ FTpust# 
nQ SASSQZ/ooxs,, epnTout# 
H SUSWL DAXN FoOpust# 


/x H SLSIT O9Xa x/ FTpucSH 
uQ"  SASTL/O8xe,, SpnTout# 
H SLSIT OaxXa Jopust# 


/*« H SHGON O&Xa x/ FTPuSP 
uw sepou/oexe,, epnTouT# 


H SSGON OFX Jopuszt# 


/* 
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H SLYOd_OFXa PUTJEpH 

H SLYOd OFXA FoOpusTt# 
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/x ToZ sqydaoxe eyeQ TTTM om shts ,/ 
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HONOWI JL eutyep# 
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MHOWOWLS JL eutyep}# 
USWLA_dL eutzep¥ 
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HONOWI_ GL eutyep# 

HOLIMS dL eutzep}# 
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MHOWOVLS AL eutzop# 

USWVLA_GL eutyop# 
ANILOOUd aL 

sqtq beta 


/eyeqiespn 34 ULI 
‘AxQug™uey Of.98TT yonz4As 
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/* nad Bbutsot yxseQ ,/ /() (G4TMS 23x) aIOA 
/xZ + punoq xzeddn yoeqs ,/ ‘zeddnds 23 ULadw 
/* punoq 2eMOT yoReAS x/ /TEMOTES 33 ULdw 
/* zequtod yoreqs ,/ ‘Bbeuds_ 23 ULadw 
/x B3ep dezy 03 squtod ,/ ‘epoodezy 23 ULdw 
/x epod derzqy oq squtod ,/ feqjeqdezy 93 ULaw 
/x @pod jAdeoxse oj squtod ,/ fepopjdeszg 93 ULadwW 
/x BRep jadaoxse of squtod ,/ feqeqqdeoxg 23 ULaw 
/x petqeue sdezq ,/ etqudezy 53 qaaomoa 
/x peqecootte sdexz ,/ fpejTtwdezpn 23 CYOMa 
iqdeoxg6ts 52 SNOTIN 
/x PeATedex eaey om shts ,/ ipaseybts 23 SNO1TO 
/x xoy Butyjtem eze om shts ,/ ‘atemBits 23 © ©65NO7TN 
/+ pezeootte sbhts ,/ /D0TTWBts_ 23 8 8©SNOTN 
/xbuyqseu petqestp yseq x/ /quo3seNdL 23 ALA 
/x5utyseu peTqestp r3uT ,/ /3uD34seNdI_ 23 ALA 
29248 93 aLAGOA 
‘sheyTa 220©«=6-ALAGON 
J@PON 23 epoN AoONnIAAS 
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/x 
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H SLSITI OUXA Fopust# 
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/* 
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HH 
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%% 
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Assembly language include files 


This section contains the 68000 assembly language include files from the operating system source code. 
Whenever the system software requires that a certain structure or constant, it will be defined here. Each 


subsystem has its own include files. 


As with the C language include files, this section is for reference only. Similar include files generally 
come on disk with whatever assembler you may choose to use with the Amiga. It is important to keep in 


mind that the include files that come with your assembler may not be an exact match to the files listed 


here. 





Listed below is a simple example of an assembly language program which uses the header file dos.h. 


A quick example of using an assembly language include file. The 
constant “RETURN FAIL" is not defined in this example, instead the 
value is pulled from the "libraries/dos.i" include file. This is 


equivalent to: 


moveg #20,da0 
rts 


+ + + + + + F 


INCLUDE "“libraries/dos.i" 


moveq #RETURN FAIL,D0O 
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Reference charts 


This section contains several handy reference charts. These are often useful when searching memory or 


scanning structures during debugging. The charts are: 


QO 2.04 Function Offsets - The Amiga libraries are listed, with a separate entry for each library function. 
The chart lists the function’s negative offset from the library base and a short summary of register 


usage. 


L) 2.04 Structure Reference - All structures in the Amiga system include files are listed alphabetically 
along with their sizes and the offset of each field within the structure given in hex and decimal. 
An exclamation point in front of the entry indicates a longword field which is not 


longword-aligned. 


LJ C Language Cross Reference - Each element from the Amiga include files is listed along with its 
resolved value, the location where it was defined (indicated by *), and each place that references 
it. Since the elements in the assembly language include files have similar names, this chart is also 


useful for assembly language programmers. 
(J Amiga Function Index - This is an alphabetical listing of all the functions, device commands, and 


macros covered in this book showing the page number where you can find each one. Also listed 


is the name of the library, device, or resource where the function is located. 
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: perb graphics, sound 

multiwindow and multitasking capabilities. oe: 
technologically advanced hardware is designed around 
the Motorola 68000 microprocessor family and 
sophisticated custom chips. The Amiga’s unique system 
software provides programmers with bbohey-va-v Olive mm 
power, flexibility, and convenience in (Sioa ee etem-varal 
| creating programs. 

This manual is the definitive source of information on the routines and data structures 

in the Amiga’s operating system. This new edition has been updated to include the hundreds 

of new system functions and structures in Release 2. It includes: | 


* Function descriptions for each Library, Device, and Resource call in the system 
* Complete listings of the Amiga’s C and Assembly language include files 

* Documentation and source code for functions in the amiga.lib linker library 

° Cross-reference charts to help you find the Amiga information you need 


Written by the technical experts at Commodore-Amiga, Inc., the Dre ROM Kernel Reference 
Manual: Includes and Autodocs is an essential reference tool for all Amiga programmers who 
want to take full advantage of the Amiga’s impressive capabilities. 


The new AMIGA TECHNICAL REFERENCE SERIES has been revised and updated to provide a 
comprehensive reference and tutorial for the entire line of Amiga computers and for Release 2 of 
the operating system. Other titles in the series include: 


Amiga User Interface Style Guide 

i Amiga ROM Kernel Reference Manual: Devices 
Amiga ROM Kernel Reference Manual: Libraries 
Amiga Hardware Reference Manual 
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